<HTML><HEAD><TITLE>source_read(+SourcePos, -NextPos, -Kind, -SourceTerm)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(source_processor)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>source_read(+SourcePos, -NextPos, -Kind, -SourceTerm)</H1>
Read the next term from an open ECLiPSe source file
<DL>
<DT><EM>SourcePos</EM></DT>
<DD>Source position handle
</DD>
<DT><EM>NextPos</EM></DT>
<DD>Source position handle
</DD>
<DT><EM>Kind</EM></DT>
<DD>kind of source term (atom)
</DD>
<DT><EM>SourceTerm</EM></DT>
<DD>a source_term structure
</DD>
</DL>
<H2>Description</H2>
This reads the next source term from a source file previously
    opened with source_open/3. The term at the current source position
    SourcePos is read, and the next source position is returned for use
    in subsequent source_read/4 invocations (it is not possible to read
    twice from the same source position!).
    <P>
    The term that has been read is classified into one of the following
    categories (Kind):
    <DL>
    <DT>handled_directive</DT>
    	<DD>A directive (a term with functor :-/1) which has already
	been handled (interpreted by source_read/3). Such directives are:
	module/1,3, local/1, export/1, reexport/1, use_module/1, lib/1,
	pragma/1, include/1, ./2, op/3, meta_attribute/2 and
	comment(include,...)</DD>
    <DT>directive</DT>
    	<DD>A directive (a term with functor :-/1) which has not
	been handled (ignored by source_read/3)</DD>
    <DT>query</DT>
    	<DD>A query (a term with functor ?-/1)</DD>
    <DT>clause</DT>
    	<DD>Any other structure, list or atom (usually a clause)</DD>
    <DT>var</DT>
    	<DD>A term consisting of only a variable (very likely an error)</DD>
    <DT>other</DT>
    	<DD>A number, string, etc (very likely an error)</DD>
    <DT>comment</DT>
    	<DD>Spacing, layout and comments between source terms
    	(only when keep_comments option is in effect)</DD>
    <DT>end_include</DT>
    	<DD>The end of an included source file</DD>
    <DT>end</DT>
    	<DD>The end of the (top-level) source file</DD>
    </DL>
    The information about the source term itself is returned as a structure
    <PRE>
    :- export struct(source_term(
	term,		% the read term itself
	vars,		% list of [VarName|Var] pairs (as in readvar/3)
	annotated       % the read term with type and source annotations 
	...
    )).
    </PRE>
    For category 'comment', the term is a string containing the comment.
    For category 'end' and 'end_include', the term is the atom end_of_file.
    In all these cases, vars is the empty list, and annotated is
    uninstantiated.
    <P>
    Note that either the vars-field or the annotated field is valid,
    depending on the setting of the with_annotations-option.  If the option
    is set, the vars field contains an empty list, and the annotated term
    is in the same format as that returned by read_annotated/2, i.e. a
    recursive wrapper structure around the read term of the following format:
<PRE>
    :- export struct(annotated_term(
        term,                   % var, atomic or compound
                                % args of compound terms are annotated
        type,                   % term type (see below)
        file,                   % file name (atom)
        line,                   % line number (integer >= 1)
        from, to                % source position (integers >= 0)
        ...
    )).
</PRE>
    If the with_annotations-option is not set, the annotated-field remains
    uninstantiated, and the vars-field is a list as detailed in readvar/3.
    <P>
    Notes on module handling:  When source_read/3 encounters a
    module-directive (which is a handled_directive), the corresponding
    module is implicitly created (unless it exists already, in which
    case it is either reused or erased and re-created, depending on
    the setting of the recreate_modules option), and that
    module becomes the context module for any subsequently read
    clauses or directives.  By default, source_close/2 removes these
    modules again in order to restore the original state.
    
<H2>See Also</H2>
<A HREF="../../lib/source_processor/source_open-3.html">source_open / 3</A>, <A HREF="../../lib/source_processor/source_close-2.html">source_close / 2</A>, <A HREF="../../kernel/ioterm/readvar-3.html">readvar / 3</A>, <A HREF="../../kernel/ioterm/read_annotated-2.html">read_annotated / 2</A>
</BODY></HTML>
